Skip to main content

Near Real-Time Device Status

Background

The deviceStream API is a scalable GraphQL Subscription API that enables real-time monitoring of various key attributes of Poly devices and provides an update when their values change. Most notably, this includes the connection status between Poly devices and the Poly Lens cloud. If a device disconnects from the Poly Lens cloud, it likely means the device has stopped working and is no longer connected to the outside network.

With this API, you can monitor multiple devices at once using a single GraphQL Subscription stream, making it an effective tool for overseeing devices in VIP rooms, spotting devices with connectivity problems as soon as they run into issues, or any scenario where prompt alerts are crucial.

Arguments

The deviceStream subscription API needs the following arguments. The values are case-sensitive.

ArgumentDescriptionType
deviceIdsUnique identifier of the device(s) you want to monitor; Array type argument; Accepts multiple device IDs to monitor[String!]!

Fields

The deviceStream subscription API returns the following fields.

FieldDescriptionType
connectedConnection status between Poly device and Poly Lens cloudBoolean
externalIpExternal IP address of the deviceString
hardwareRevisionRevision number of the device's hardware.String
idUnique identifier of the deviceString!
macAddressMac address of the deviceString
modelIdUnique model name or number of the deviceString
nameOfficial name of product without manufacturer name, e.g. Studio P15String
productIdProduct identifier of the deviceString
roomIdUnique identifier of the roomString
siteIdUnique identifier of the siteString
softwareBuildUnique identifier of the ‘build’ of the device software. This helps differentiate different builds within the same version.String
softwareVersionProduct software versionString
tenantIdThe Poly Lens account identifier of the deviceString

deviceStream Subscription API in the Poly Lens GraphQL Playground - Monitoring Device Connection Status

Let's consider a scenario where you need to be promptly notified if a device in a VIP room loses its connection to the Poly Lens cloud, likely indicating that the device may no longer be operational. To monitor for connectivity state changes, you can use the following query.

Test this subscription in the GraphQL Playground

subscription DeviceStream($deviceIds: [String!]!) {
deviceStream(deviceIds: $deviceIds) {
connected
id
}
}

Arguments passed for the above query

{
"deviceIds": [
"xxxxxxxxxxxxxxxxxxxxxxxxxxxx240e",
"xxxxxxxxxxxxxxxxxxxxxxxxxxxx35f0"
]
}

Important Note: The API stream is engineered to track state changes across multiple devices simultaneously. To prevent exceeding rate limits, it's highly recommended to use a single API stream for multiple devices. This can be achieved by listing device IDs separated by commas within an array, as illustrated in the example above.

Response for the above query

If you disconnect one of the devices, the Poly Lens deviceStream Subscription API will return a response with the value of the connected field as false. Then, when you reconnect the device, the API will return a response with the value of the connected field as true.

// Response received at 21:15:50
{
"data": {
"deviceStream": {
"connected": true,
}
}
}

// Response received at 21:04:31
{
"data": {
"deviceStream": {
"connected": false,
"id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx35f0"
}
}
}

The deviceStream Subscription API in the Poly Lens GraphQL Playground – Monitoring Other Attributes

If you want to monitor certain devices for changes in the rooms or sites (with which those devices are associated), or for changes in device software version, etc., you can do it using this API. You can monitor for changes in values of any of the fields in this API. See the following example.

Test this subscription in the GraphQL Playground

subscription DeviceStream($deviceIds: [String!]!) {
deviceStream(deviceIds: $deviceIds) {
connected
externalIp
hardwareRevision
id
macAddress
modelId
name
productId
roomId
siteId
softwareBuild
softwareVersion
tenantId
}
}

Arguments passed for the above query

{
"deviceIds": ["xxxxxxxx3ef4"]
}

Important Note: The API stream is engineered to track state changes across multiple devices simultaneously. To prevent exceeding rate limits, it's highly recommended to use a single API stream for multiple devices. This can be achieved by listing device IDs separated by commas within an array, as illustrated in the example above.

Response for the above query

If you move a device from a certain room at a certain site to a different room at a different site, the deviceStream Subscription API will return a response with updated values for the fields roomId and siteId.

// Response received at 20:26:46
{
"data": {
"deviceStream": {
"connected": true,
"externalIp": "xx.xxx.xxx.70",
"hardwareRevision": "7",
"id": "xxxxxxxx3ef4",
"macAddress": "xx:xx:xx:xx:xx:f4",
"modelId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx18a8",
"name": "G7500",
"productId": "G 7500",
"roomId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxc4f1",
"siteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxf199",
"softwareBuild": "1011026",
"softwareVersion": "4.1.0",
"tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx8028"
}
}
}

// Response received at 20:20:27
{
"data": {
"deviceStream": {
"connected": true,
"externalIp": "xx.xxx.xxx.70",
"hardwareRevision": "7",
"id": "xxxxxxxx3ef4",
"macAddress": "xx:xx:xx:xx:xx:f4",
"modelId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx18a8",
"name": "G7500",
"productId": "G 7500",
"roomId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx7c2a",
"siteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx09fa2",
"softwareBuild": "xxx1026",
"softwareVersion": "4.1.0",
"tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx8028"
}
}
}

Summary

If you have questions about usage, authentication, or integration with the Poly Lens APIs, contact us.